Background Runs

BindAI v0.1 provides a REST API for submitting automation runs for background execution. Background runs allow a client to submit work without keeping the original HTTP request open until the automation completes. The API provides two endpoints:

POST /api/v1/runs
GET /api/v1/runs/{run_id}

The first endpoint submits a run. The second endpoint retrieves the current or completed state of a run.

Background Run Architecture

The v0.1 architecture is:

Client
   |
   | POST /api/v1/runs
   v
BindAI API
   |
   v
AutomationWorker
   |
   v
AutomationDefinition
   |
   v
AutomationRun

The client receives a run identifier and can later use that identifier to inspect the run. Conceptually:

Submit
   |
   v
Run ID
   |
   v
Background Execution
   |
   +---- Running
   |
   +---- Completed
   |
   +---- Failed

The exact run state is determined by the current AutomationRun implementation.

Authentication

Background-run endpoints are protected by the BindAI API authentication layer. Clients must provide:

Authorization: Bearer <API key>

For example:

curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/runs/example-run

The API key is configured through:

BINDAI_API_KEY=your-secret-key

See the Authentication page for details.

Submit a Background Run

A new background run is submitted with:

POST /api/v1/runs

The request body contains:

{
  "automation_id": "my-automation",
  "input": {
    "message": "Process this request"
  }
}

The automation_id identifies an automation definition that has already been configured in the BindAI API application. The input field is optional and can contain application-specific data. The current API stores the supplied input on the resulting AutomationRun. It should not be assumed that the current automation worker automatically passes this input into AutomationDefinition.run(). Applications should treat the stored run input and the automation definition’s execution input as separate concerns until explicit input propagation is implemented.

Example Request

Using cURL:

curl \
  -X POST \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "automation_id": "my-automation",
    "input": {
      "message": "Process this request"
    }
  }' \
  http://localhost:8000/api/v1/runs

The API looks up the configured automation and submits it to the AutomationWorker.

Submission Response

A successful submission returns HTTP 202 Accepted. The response contains information about the created run. A response can look like:

{
  "id": "run-id",
  "definition_id": "my-automation",
  "definition_version": 1,
  "status": "pending",
  "input": {
    "message": "Process this request"
  },
  "output": null,
  "error": null,
  "created_at": "2026-01-01T12:00:00Z",
  "started_at": null,
  "completed_at": null
}

The exact values depend on the current execution state. The returned id is the run identifier used to query the run later.

HTTP 202 Accepted

Background execution uses HTTP 202 Accepted because the request submits work for execution rather than waiting for the automation to finish. The request lifecycle is:

HTTP Request
     |
     v
Validate Request
     |
     v
Find Automation
     |
     v
Create Run
     |
     v
Submit to Worker
     |
     v
202 Accepted
     |
     v
Background Execution

The client should not interpret 202 Accepted as successful completion of the automation. It means that the run has been accepted for background execution.

Get Run Status

A submitted run can be inspected with:

GET /api/v1/runs/{run_id}

For example:

curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/runs/run-id

The API checks the available automation worker state and run history and returns the stored run state when the run is available.

Run Response

A run response contains fields corresponding to the AutomationRun model:

id
definition_id
definition_version
status
input
output
error
created_at
started_at
completed_at

A completed run can look like:

{
  "id": "run-id",
  "definition_id": "my-automation",
  "definition_version": 1,
  "status": "completed",
  "input": {
    "message": "Process this request"
  },
  "output": {
    "result": "completed"
  },
  "error": null,
  "created_at": "2026-01-01T12:00:00Z",
  "started_at": "2026-01-01T12:00:01Z",
  "completed_at": "2026-01-01T12:00:05Z"
}

The exact output depends on the automation definition. Clients should use the returned status rather than assuming a particular state immediately after submission.

Run Lifecycle

The AutomationWorker creates an AutomationRun before submitting background execution. The run is then updated as execution progresses. Conceptually:

Run Created
    |
    v
Run Started
    |
    +--------> Completed
    |
    +--------> Failed

The run contains timestamps that describe this lifecycle:

created_at
    |
    v
started_at
    |
    v
completed_at

Some timestamps may be null while a run is still in progress.

Polling

A client can poll the run endpoint until execution reaches a terminal state. For example:

POST /api/v1/runs
       |
       v
    run-id
       |
       v
GET /api/v1/runs/{run-id}
       |
       +---- running ------+
       |                   |
       |                   v
       |              GET again
       |
       +---- completed
       |
       +---- failed

A client should use a sensible polling interval rather than repeatedly requesting the endpoint as quickly as possible. For workloads with many long-running executions, a dedicated application-level notification mechanism may be more appropriate.

Python Client Example

A Python application can submit a background run using an HTTP client. For example:

import requests

base_url = "http://localhost:8000"

headers = {
    "Authorization": "Bearer your-secret-key",
    "Content-Type": "application/json",
}

response = requests.post(
    f"{base_url}/api/v1/runs",
    headers=headers,
    json={
        "automation_id": "my-automation",
        "input": {
            "message": "Process this request",
        },
    },
)

response.raise_for_status()

run = response.json()
run_id = run["id"]

print(f"Run submitted: {run_id}")

The client can then query the run:

status_response = requests.get(
    f"{base_url}/api/v1/runs/{run_id}",
    headers={
        "Authorization": "Bearer your-secret-key",
    },
)

status_response.raise_for_status()

print(status_response.json())

JavaScript Example

A JavaScript application can submit a run using fetch:

const response = await fetch(
  "http://localhost:8000/api/v1/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer your-secret-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      automation_id: "my-automation",
      input: {
        message: "Process this request",
      },
    }),
  },
);

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const run = await response.json();

console.log("Run ID:", run.id);

The returned run ID can then be used to retrieve execution state.

Run Input

The submission request supports an optional input value:

{
  "automation_id": "my-automation",
  "input": {
    "customer_id": "123",
    "operation": "process"
  }
}

The supplied value is stored on the AutomationRun. The meaning of the input is application-specific. An important v0.1 detail is that the current AutomationWorker stores this input on the run but invokes the automation definition using:

definition.run()

It does not currently call:

definition.run(input)

Therefore, the API’s input field should currently be understood as run metadata/state, not as an automatic argument passed to the automation definition. Applications that require input-driven execution should explicitly connect their input data to the automation’s execution logic.

Automation Definition

The automation_id identifies an automation definition configured in the BindAI application. Conceptually:

automation_id
      |
      v
AutomationDefinition
      |
      v
AutomationWorker
      |
      v
AutomationRun

The API does not dynamically create arbitrary automation definitions from the HTTP request. The automation must already be configured and available to the BindAI API application.

Definition Version

Background runs include the automation definition version. This allows a run to identify the version of the automation definition associated with it. For example:

{
  "definition_id": "daily-report",
  "definition_version": 3
}

This information can be useful when diagnosing executions after an automation definition has changed.

Run State

The run contains execution metadata such as:

id
definition_id
definition_version
status
created_at
started_at
completed_at

The timestamps provide a basic execution timeline:

created_at
    |
    v
started_at
    |
    v
completed_at

Not every timestamp is necessarily available at every stage. For example, a newly created run may not yet have a started_at or completed_at value.

Successful Runs

A completed run can contain an output value. Conceptually:

{
  "status": "completed",
  "output": {
    "result": "success"
  },
  "error": null
}

The output format depends on the automation. Clients should not assume that every automation returns the same structure.

Failed Runs

A failed run can contain an error description. Conceptually:

{
  "status": "failed",
  "output": null,
  "error": "Automation execution failed."
}

A failed run represents an automation execution failure rather than an authentication or HTTP submission failure. For example:

Valid API key
      |
      v
Run accepted
      |
      v
Automation execution
      |
      v
Failure

The API authentication can therefore succeed even when the background automation itself fails. The worker records exceptions from automation execution as run failures.

Run Not Found

If a requested run does not exist in the available worker state or history, the API returns a not-found response. For example:

GET /api/v1/runs/unknown-run

results in:

404 Not Found

Clients should handle missing run IDs separately from failed executions.

Background Worker

The v0.1 API uses an AutomationWorker for background execution. The worker uses an in-process ThreadPoolExecutor. Its responsibilities include:

creating AutomationRun instances
persisting run state
submitting background work
updating run lifecycle state
recording completed or failed runs in history

Conceptually:

BindAI API Process

+-- FastAPI
|
+-- AutomationWorker
      |
      +-- Thread
      +-- Thread
      +-- Thread
      +-- Thread

The default worker configuration uses four worker threads. Applications can configure the worker separately when using it directly.

Worker Submission

The worker exposes two related background-submission operations. The simple form returns a Future:

future = worker.submit(
    automation,
    input=payload,
)

run = future.result()

The lower-level form returns both the run and future immediately:

run, future = worker.submit_with_run(
    automation,
    input=payload,
)

submit_with_run() persists the newly created AutomationRun before background execution starts. This allows the API to return the run information without waiting for the automation to complete.

Synchronous Worker Execution

AutomationWorker also supports synchronous execution:

run = worker.run(
    automation,
    input=payload,
)

This executes the automation in the current thread. The REST background-run endpoint uses background submission rather than synchronous execution.

Process-Local Execution

The most important v0.1 limitation is that the worker is process-local. The worker exists inside the application process:

Application Process

+---- BindAI API

+---- AutomationWorker
         |
         +---- Background Run

It is not a separate distributed worker service.

What Process-Local Means

If the application process stops, background work running inside that process can be interrupted. For example:

Application
    |
    v
Background Run
    |
    X
Process Stops

The run is not automatically transferred to another server or worker process. This behavior is acceptable for the initial v0.1 deployment model but should be considered when designing production workloads.

No Distributed Queue

The v0.1 background-run implementation does not provide a distributed message queue. It does not automatically coordinate:

API Instance A
       |
       +---- Worker A

API Instance B
       |
       +---- Worker B

Each process has its own worker. There is no built-in cross-process coordination between these workers.

Horizontal Scaling

Running multiple API instances does not automatically create one shared background execution system. For example:

Load Balancer
      |
      +---- API Instance A
      |         |
      |         +---- Worker A
      |
      +---- API Instance B
                |
                +---- Worker B

Worker A and Worker B operate independently. A production deployment that requires coordinated background execution should introduce a persistent queue and dedicated workers.

Durable Execution

The v0.1 worker should not be considered a durable distributed job system. Durable execution generally requires persistent state and coordination outside the application process. A future architecture can look like:

Client
   |
   v
BindAI API
   |
   v
Persistent Queue
   |
   +---- Worker A
   +---- Worker B
   +---- Worker C
   |
   v
Persistent Run State

This architecture allows work to be coordinated across multiple processes and machines. That capability is outside the v0.1 scope.

Background Runs vs Streaming

Background runs and streaming serve different purposes. Background runs:

Client
   |
   v
Submit
   |
   v
Run ID
   |
   v
Background Execution

Streaming:

Client
   |
   v
Agent
   |
   +---- Output
   +---- Output
   +---- Output

Use background runs when the client does not need to maintain a live response connection. Use streaming when the client wants to consume agent output progressively. See the Streaming page for the streaming API.

Background Runs vs Synchronous Execution

Synchronous execution keeps the request open while execution completes.

Client
   |
   v
API
   |
   v
Execution
   |
   v
Complete Result
   |
   v
Client

Background execution separates submission from execution:

Client
   |
   v
API
   |
   v
Run ID
   |
   v
Background Execution

This can be useful for longer-running operations.

Background Runs and Automation Scheduling

Background runs are different from scheduled automation. A background run is explicitly submitted through the API:

HTTP Request
    |
    v
Background Run

A scheduled automation is triggered according to an application’s scheduling configuration:

Scheduler
    |
    v
Automation

Scheduling and background execution can be combined, but they represent different concerns.

Background Runs and Observability

Background executions can produce runtime events through BindAI’s event system. Relevant events can include:

agent events
workflow events
node events
model events
tool events
memory events

BindAI Runtime also provides an in-memory EventRecorder for recording events emitted through an execution context’s event bus. This can support:

debugging
execution inspection
custom logging
future metrics integrations
future tracing integrations

The event recorder is not a distributed background-run state store. These are separate concerns:

Background Run Execution
        |
        v
AutomationWorker


Execution Events
        |
        v
EventBus / EventRecorder

Error Handling

Background execution can fail for the same reasons as other BindAI executions. Potential failures include:

model provider errors
tool errors
workflow errors
connection failures
external-service failures
invalid automation configuration
application errors

The worker records execution failures on the AutomationRun. Clients should inspect the run’s status and error fields rather than assuming that a successfully submitted run will always complete successfully.

Retries

The current AutomationWorker does not automatically retry failed runs. Retry behavior, where supported by higher-level automation or workflow configuration, should be treated separately from the worker’s basic execution lifecycle. Clients should not blindly resubmit failed background runs. For example:

Run
 |
 +---- Failure
        |
        v
     Retry?
        |
        +---- Yes
        |
        +---- No

Particular care is required for operations with external side effects. A repeated run can create duplicate external operations if the original execution actually succeeded but its final state was not observed.

Idempotency

Background operations should be designed with idempotency in mind. This is especially important when an automation performs:

API writes
notifications
emails
database updates
deployment operations
ticket creation
external workflow changes

Before retrying a run, determine whether repeating its external operations is safe. Where an external service supports idempotency keys, applications should use them when appropriate.

Security

Background runs can execute tools and connections with access to external services. Protect the run endpoints accordingly. Recommended practices include:

use strong API keys
use HTTPS
protect external credentials
limit connection permissions
validate automation inputs
avoid exposing secrets through run input or output
avoid logging sensitive run data
restrict access to state-changing automations

A valid API key provides access to the configured background-run API surface, so the API key should be treated as a privileged credential.

Input and Output Data

Run input and output can contain application data. For example:

Client Input
    |
    v
Background Run
    |
    v
Automation
    |
    v
Run Output

Applications should consider whether this data contains:

personal information
credentials
internal identifiers
confidential business data
external-service responses

Do not expose sensitive run data unnecessarily. Remember that the current worker stores submitted input on the run but does not automatically pass it to AutomationDefinition.run().

Production Considerations

Before using background runs in production, consider:

process lifetime
deployment restarts
container restarts
worker capacity
execution duration
external-service reliability
retry behavior
idempotency
monitoring
run-state persistence
failure recovery

The process-local worker is suitable for the initial v0.1 deployment foundation but is not intended to replace a durable distributed job system.

Docker

Background runs work inside the same BindAI API container when using the v0.1 Docker deployment. Conceptually:

Docker Container

+---- BindAI API
|
+---- AutomationWorker
         |
         +---- Background Run

If the container stops, in-process background work can be interrupted. Running additional containers does not automatically create a coordinated worker pool.

Docker Compose

Docker Compose can run the BindAI API locally:

docker compose up --build

The background worker runs inside the API process according to the v0.1 architecture. This is suitable for local development and simple deployments. A distributed production worker architecture requires additional infrastructure beyond the current Compose setup.

API Health vs Run Health

The /health endpoint indicates basic API service availability:

GET /health

It does not indicate that a particular background run is successful. These are separate checks:

/health
   |
   v
API Service Health


/api/v1/runs/{run_id}
   |
   v
Specific Run State

A healthy API can contain failed background runs. Likewise, a particular run can fail while the API itself remains healthy.

Testing

The API package includes tests for the background-run endpoints. Run the API tests with:

uv run pytest packages/bindai-api/tests -q

The broader repository tests can be run with:

uv run pytest tests -q

Automation worker behavior is tested at the automation package level:

uv run pytest packages/bindai-automation/tests -q

Relevant tests should cover:

run submission
run lookup
authentication
missing runs
successful execution
failed execution
worker submission
synchronous worker execution
run state transitions
history recording

Current v0.1 Scope

BindAI v0.1 provides:

background run submission
run identifiers
run status lookup
run input storage
run output
run errors
creation timestamps
start timestamps
completion timestamps
in-process automation workers
thread-pool background execution
API-key authentication

The implementation is intentionally lightweight.

Current Limitations

The v0.1 background-run system does not provide:

distributed queues
durable distributed workers
cross-instance worker coordination
Kubernetes-native job execution
built-in worker autoscaling
managed cloud workers
guaranteed execution after process failure
a distributed run-state database
automatic worker retries
dead-letter queues

These capabilities are outside the initial v0.1 scope.

Future Distributed Execution

A future BindAI architecture can introduce a persistent queue:

Client
   |
   v
BindAI API
   |
   v
Persistent Queue
   |
   +---- Worker A
   +---- Worker B
   +---- Worker C
   |
   v
Persistent Run State

Such an architecture could provide:

durable job submission
worker coordination
multiple worker processes
multiple worker machines
retry recovery
queue monitoring
horizontal scaling
better process-failure recovery

Queue-based execution is planned for a future BindAI release and is not required for v0.1.

Recommended Usage

For v0.1, background runs are appropriate when:

the work can execute inside the API process
losing in-process work during a process restart is acceptable
a lightweight background execution model is sufficient
the deployment does not require coordinated workers
the application can handle the current persistence limitations

For workloads requiring durable distributed execution, use an external job system or wait for a future BindAI queue-based execution architecture.

Example End-to-End Flow

A complete background-run flow can look like:

1. Client
      |
      | POST /api/v1/runs
      v
2. BindAI API
      |
      | Validate API key
      v
3. Find AutomationDefinition
      |
      v
4. AutomationWorker
      |
      | Submit execution
      v
5. AutomationRun
      |
      v
6. Background Execution
      |
      +---- Agent
      +---- Workflow
      +---- Tool
      +---- Connection
      |
      v
7. Run State / History
      |
      v
8. Client
      |
      | GET /api/v1/runs/{run_id}
      v
9. Result

The client does not need to keep the original submission request open while the automation executes.

Summary

BindAI v0.1 provides background automation execution through:

POST /api/v1/runs
GET /api/v1/runs/{run_id}

A client submits an automation and receives a run ID:

Submit
  |
  v
Run ID

The client can then retrieve the run state:

Run ID
  |
  v
Run Status
  |
  +---- Running
  +---- Completed
  +---- Failed

The current implementation uses an in-process AutomationWorker backed by a thread pool. The worker creates and tracks AutomationRun instances, executes automation definitions in background threads, persists state, and records completed or failed runs in history. The current API’s input value is stored on the run. It is not automatically passed as an argument to AutomationDefinition.run() by the current worker implementation. The most important deployment limitation is:

Application Process
       |
       v
AutomationWorker
       |
       v
Background Run

If the application process stops, in-process work can be interrupted. Distributed queues, coordinated workers, durable execution, and Kubernetes-based worker infrastructure are intentionally deferred beyond the v0.1 release. For the initial public release, the background-run API provides a simple way to submit and inspect automation work while keeping the deployment architecture lightweight.

​Background Runs

​Background Run Architecture

​Authentication

​Submit a Background Run

​Example Request

​Submission Response

​HTTP 202 Accepted

​Get Run Status

​Run Response

​Run Lifecycle

​Polling

​Python Client Example

​JavaScript Example

​Run Input

​Automation Definition

​Definition Version

​Run State

​Successful Runs

​Failed Runs

​Run Not Found

​Background Worker

​Worker Submission

​Synchronous Worker Execution

​Process-Local Execution

​What Process-Local Means

​No Distributed Queue

​Horizontal Scaling

​Durable Execution

​Background Runs vs Streaming

​Background Runs vs Synchronous Execution

​Background Runs and Automation Scheduling

​Background Runs and Observability

​Error Handling

​Retries

​Idempotency

​Security

​Input and Output Data

​Production Considerations

​Docker

​Docker Compose

​API Health vs Run Health

​Testing

​Current v0.1 Scope

​Current Limitations

​Future Distributed Execution

​Recommended Usage

​Example End-to-End Flow

​Summary